.\"	$OpenBSD: malloc.conf.5,v 1.1 2014/12/06 18:54:55 schwarze Exp $
.\"
.\" Copyright (c) 2012 Damien Miller <djm@openbsd.org>
.\" Copyright (c) 2008, 2009, 2010, 2011 Otto Moerbeek <otto@drijf.net>
.\" Copyright (c) 2003, 2004, 2005 Ted Unangst <tedu@openbsd.org>
.\" Copyright (c) 1995, 1996 Poul-Henning Kamp <phk@freebsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: December 6 2014 $
.Dt MALLOC.CONF 5
.Os
.Sh NAME
.Nm malloc.conf
.Nd options for the memory allocator
.Sh DESCRIPTION
The memory allocator functions of the
.Xr malloc 3
family first look for a symbolic link called
.Pa /etc/malloc.conf
and next check the environment for a variable called
.Ev MALLOC_OPTIONS
and finally for the global variable
.Va malloc_options
and scan them for flags in that order.
Flags are single letters, uppercase means on, lowercase means off.
.Bl -tag -width indent
.It Cm A
.Dq Abort .
.Xr malloc 3
will coredump the process, rather than tolerate internal
inconsistencies or incorrect usage.
This is the default and a very handy debugging aid,
since the core file represents the time of failure,
rather than when the bogus pointer was used.
.It Cm D
.Dq Dump .
.Xr malloc 3
will dump statistics to the file
.Pa ./malloc.out ,
if it already exists,
at exit.
This option requires the library to have been compiled with -DMALLOC_STATS in
order to have any effect.
.It Cm F
.Dq Freeguard .
Enable use after free detection.
Unused pages on the freelist are read and write protected to
cause a segmentation fault upon access.
This will also switch off the delayed freeing of chunks,
reducing random behaviour but detecting double
.Xr free 3
calls as early as possible.
This option is intended for debugging rather than improved security
(use the
.Cm U
option for security).
.It Cm G
.Dq Guard .
Enable guard pages.
Each page size or larger allocation is followed by a guard page that will
cause a segmentation fault upon any access.
.It Cm H
.Dq Hint .
Pass a hint to the kernel about pages we don't use.
If the machine is paging a lot this may help a bit.
.It Cm J
.Dq Junk .
Fill some junk into the area allocated.
Currently junk is bytes of 0xd0 when allocating; this is pronounced
.Dq Duh .
\&:-)
Freed chunks are filled with 0xdf.
.It Cm j
.Dq Don't Junk .
By default, small chunks are always junked, and the first part of pages
is junked after free.
This option ensures that no junking is performed.
.It Cm P
.Dq Move allocations within a page.
Allocations larger than half a page but smaller than a page
are aligned to the end of a page to catch buffer overruns in more
cases.
This is the default.
.It Cm R
.Dq realloc .
Always reallocate when
.Xr realloc 3
is called, even if the initial allocation was big enough.
This can substantially aid in compacting memory.
.\".Pp
.\".It Cm U
.\".Dq utrace .
.\"Generate entries for
.\".Xr ktrace 1
.\"for all operations.
.\"Consult the source for this one.
.It Cm S
Enable all options suitable for security auditing.
.It Cm U
.Dq Free unmap .
Enable use after free protection for larger allocations.
Unused pages on the freelist are read and write protected to
cause a segmentation fault upon access.
.It Cm X
.Dq xmalloc .
Rather than return failure,
.Xr abort 3
the program with a diagnostic message on stderr.
It is the intention that this option be set at compile time by
including in the source:
.Bd -literal -offset indent
extern char *malloc_options;
malloc_options = "X";
.Ed
.Pp
Note that this will cause code that is supposed to handle
out-of-memory conditions gracefully to abort instead.
.It Cm <
.Dq Half the cache size .
Decrease the size of the free page cache by a factor of two.
.It Cm >
.Dq Double the cache size .
Increase the size of the free page cache by a factor of two.
.El
.Pp
The flags are mostly for testing and debugging.
If a program changes behavior if any of these options (except
.Cm X )
are used,
it is buggy.
.Pp
The default number of free pages cached is 64.
.Sh ENVIRONMENT
.Bl -tag -width "/etc/malloc.conf"
.It Ev MALLOC_OPTIONS
string of option flags
.El
.Sh FILES
.Bl -tag -width "/etc/malloc.conf"
.It Pa /etc/malloc.conf
symbolic link to filename containing option flags
.El
.Sh EXAMPLES
Set a systemwide reduction of the cache to a quarter of the
default size and use guard pages:
.Pp
.Dl # ln -s 'G<<' /etc/malloc.conf
.Sh SEE ALSO
.Xr malloc 3
